<!DOCTYPE html>
<html lang="en-US">
    <head>
        <title>Unicode::String - String of Unicode characters (UTF-16BE) - metacpan.org</title>
        <link rel="preload" as="fetch" href="https://metacpan.org/account/login_status" crossorigin="anonymous" />
        <link href="https://metacpan.org/_assets/b8ccceeed47a0652049703d99326a9cea4933443.css" rel="stylesheet" type="text/css">
        <script src="https://metacpan.org/_assets/6bfedafe2d7caa915b7d84f61b45936818e3242e.js" type="text/javascript" defer></script>
        <link rel="alternate" type="application/rss+xml" title="Recent CPAN Uploads of Unicode-String - MetaCPAN" href="https://metacpan.org/dist/Unicode-String/releases.rss" />
        <link rel="canonical" href="./Unicode::String.html" />
        <meta name="description" content="String of Unicode characters (UTF-16BE)" />
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5">
        <link rel="shortcut icon" href="https://metacpan.org/static/icons/favicon.ico">
        <link rel="apple-touch-icon" sizes="152x152" href="https://metacpan.org/static/icons/apple-touch-icon.png">
        <link rel="search" href="https://metacpan.org/static/opensearch.xml" type="application/opensearchdescription+xml" title="MetaCPAN">
        <script>
          (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
          (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
          })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

          (function(skey, ga_id){
            ga('create', ga_id, {
              siteSpeedSampleRate : 100,
              storage             : 'none',
              clientId            : localStorage.getItem(skey)
            });
            ga(function(tracker) {
              localStorage.setItem(skey, tracker.get('clientId'));
            });
            ga('send', 'pageview');
          })('ga:clientId', 'UA-27829474-1');
        </script>
<meta name="twitter:card"        content="summary" />
<meta name="twitter:url"         content="https://metacpan.org/pod/Unicode::String" />
<meta name="twitter:title"       content="Unicode::String" />
<meta name="twitter:description" content="String of Unicode characters (UTF-16BE)" />
<meta name="twitter:site"        content="metacpan" />
    </head>
    <body>
        <nav class="navbar navbar-default" role="navigation">
            <div class="header-logo-large hidden-xs">
              <a href="https://metacpan.org/" tabindex="0">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#logo" />
                </svg>
              </a>
            </div>
            <div class="header-logo-icon visible-xs">
              <a href="https://metacpan.org/">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#dots" />
                </svg>
              </a>
            </div>
            <ul class="nav navbar-nav menu-items hidden-xs hidden-sm">
              <li><a href="https://metacpan.org/about">About</a></li>
              <li><a href="https://metacpan.org/about/sponsors">Sponsor</a></li>
              <li><a href="https://grep.metacpan.org/">grep::cpan</a></li>
              <li><a href="https://metacpan.org/recent">Recent</a></li>
              <li><a href="https://metacpan.org/about/faq">FAQ</a></li>
              <li><a href="https://metacpan.org/tools">Tools</a></li>
              <li><a href="https://fastapi.metacpan.org/">API</a></li>
            </ul>
            <ul class="nav navbar-nav navbar-right">
                <button type="button" class="searchbar-btn visible-xs visible-sm">
                    <i class="fa fa-search button-fa-icon"></i>
                </button>
                <form action="https://metacpan.org/search" class="searchbar-form visible-md visible-lg search-form form-horizontal">
                   <input type="hidden" name="size" id="metacpan_search-size" value="20">
                  <div class="form-group">
                      <div class="search-group">
                        <i class="fa fa-search"></i>
                        <input type="text" name="q" placeholder="Search the CPAN" size="41" autocorrect="off" autocapitalize="off" spellcheck="false" id="metacpan_search-input" class="form-control" value="">
                      </div>
                  </div>
                </form>
                    <li class="icon-slidepanel visible-xs visible-sm">
                      <button data-toggle="slidepanel" data-target=".slidepanel">
                        <span class="button-fa-icon">
                          <i class="fa fa-bars slidepanel-open"></i>
                          <i class="fa fa-times slidepanel-close"></i>
                        </span>
                      </button>
                    </li>
                <form action="https://metacpan.org/account/logout" method="POST" id="metacpan-logout"></form>
                <li class="dropdown logged_in" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon logged-in-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li><a href="https://metacpan.org/account/identities">Identities</a></li>
                        <li><a href="https://metacpan.org/account/profile">Profile</a></li>
                        <li><a href="https://metacpan.org/account/favorite/list">Favorites</a></li>
                        <li>
                            <a href="./Unicode::String.html#" type="button" onclick="$('#metacpan-logout').submit(); return false">
                              Logout
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_out" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li>
                            <a href="https://metacpan.org/login/github">
                                <i class="fab fa-github fa-fw"></i>
                                GitHub
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/twitter">
                                <i class="fab fa-twitter fa-fw"></i>
                                Twitter
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/google">
                                <i class="fab fa-google fa-fw"></i>
                                Google
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_placeholder">
                    <button>
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                    </button>
                </li>
            </ul>
        </nav>
        <div class="page-content ">
          <!--
          <div class="top-notify-banner">
            <i class="fas fa-info-circle"></i>
          </div>
          -->
          <nav class="sidebar">
            <div class="slidepanel">
              <ul class="nav-list ">
    <li class="nav-header no-margin-top">
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The date that this version of Unicode-String was released.">
      <span class="relatize">08 Sep 2016 20:24:27 UTC</span>
    </li>
  <li>
    Distribution: <a href="https://metacpan.org/dist/Unicode-String">Unicode-String</a>
  </li>
  <li>
    Module version: 2.10
  </li>
  <li>
    <a data-keyboard-shortcut="g s" href="https://metacpan.org/dist/Unicode-String/source/String.pm">Source</a>
    (<a href="https://metacpan.org/dist/Unicode-String/source/String.pm?raw=1">raw</a>)
  </li>
  <li>
    <a data-keyboard-shortcut="g b" href="https://metacpan.org/dist/Unicode-String/source">Browse</a>
    (<a href="https://metacpan.org/dist/Unicode-String/source?raw=1">raw</a>)
  </li>
    <li>
      <a data-keyboard-shortcut="g c" href="https://metacpan.org/dist/Unicode-String/changes">Changes</a>
    </li>
    <li>
      <a class="nopopup" href="https://metacpan.org/dist/Unicode-String/contribute">How to Contribute</a>
    </li>
    <li>
      <a rel="noopener nofollow" data-keyboard-shortcut="g i" href="https://rt.cpan.org/Public/Dist/Display.html?Name=Unicode-String">Issues</a>
      (3)
    </li>
    <li>
      <a rel="noopener nofollow" href="http://matrix.cpantesters.org/?dist=Unicode-String+2.10" title="Matrix">Testers</a>
        <span title="(pass / fail / na)">(<a rel="noopener nofollow" href="https://www.cpantesters.org/distro/U/Unicode-String.html?oncpan=1&amp;distmat=1&amp;version=2.10&amp;grade=2" style="color: #090">1776</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/U/Unicode-String.html?oncpan=1&amp;distmat=1&amp;version=2.10&amp;grade=3" style="color: #900">0</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/U/Unicode-String.html?oncpan=1&amp;distmat=1&amp;version=2.10&amp;grade=4">0</a>)</span>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpants.cpanauthors.org/release/GAAS/Unicode-String-2.10">Kwalitee</a>
    </li>
    <li>
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The # people with an indexing permission on Unicode-String who have released something to CPAN in the last 2 years (i.e. the # people likely able to release critical fixes in a timely manner)">
      Bus factor: 0
      </div>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpancover.com/latest/Unicode-String-2.10/index.html">78.33% Coverage </a>
    </li>
    <li>
      License: unknown
    </li>
    <li class="nav-header">Activity</li>
    <li>
<div class="activity-graph">
    <img src="https://metacpan.org/dist/Unicode-String/activity.svg?res=month" />
    <div class="comment">24 month</div>
</div>
    </li>
    <li class="nav-header">Tools</li>
    <li>
      <a itemprop="downloadUrl" href="https://cpan.metacpan.org/authors/id/G/GA/GAAS/GAAS/Unicode-String-2.10.tar.gz">
      Download (<span itemprop="fileSize">118.44KB</span>)</a>
    </li>
    <li>
      <a href="https://explorer.metacpan.org/?url=%2Fmodule%2FGAAS%2FUnicode-String-2.10%2FString.pm">
        MetaCPAN Explorer
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Unicode-String/permissions">
        Permissions
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Unicode-String/releases.rss">
        Subscribe to distribution
      </a>
    </li>
    <li>
      <button class="btn btn-link" data-toggle="modal" data-target="#metacpan_install-instructions-dialog">
        Install Instructions
      </button>
    </li>
    <li>
      <form action="https://metacpan.org/search">
        <input type="hidden" name="q" value="dist:Unicode-String">
        <input type="search" name="q" placeholder="Search distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
      </form>
    </li>
    <li>
      <form action="https://grep.metacpan.org/search">
        <input type="hidden" name="qd" value="Unicode-String">
        <input type="hidden" name="source" value="metacpan">
        <input type="search" name="q" placeholder="grep distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
     </form>
    </li>
    <li class="version-jump">
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/String.pm&#39;" class="form-control tool-bar-form">
  <option disabled selected>Jump to version</option>
<option
  disabled
  value="GAAS/Unicode-String-2.10"
>2.10
  (GAAS on 2016-09-08)</option>
<option
  
  value="GAAS/Unicode-String-2.09"
>2.09
  (GAAS on 2005-10-26)</option>
<optgroup label="BackPAN">'
<option
  
  value="GAAS/Unicode-String-2.08"
>2.08
  (GAAS on 2005-10-25)</option>
<option
  
  value="GAAS/Unicode-String-2.07"
>2.07
  (GAAS on 2003-03-11)</option>
<option
  
  value="GAAS/Unicode-String-2.06"
>2.06
  (GAAS on 2000-05-19)</option>
<option
  
  value="GAAS/Unicode-String-2.05"
>2.05
  (GAAS on 1999-11-17)</option>
<option
  
  value="GAAS/Unicode-String-2.04"
>2.04
  (GAAS on 1999-09-14)</option>
<option
  
  value="GAAS/Unicode-String-2.03"
>2.03
  (GAAS on 1999-07-28)</option>
<option
  
  value="GAAS/Unicode-String-2.02"
>2.02
  (GAAS on 1999-05-01)</option>
<option
  
  value="GAAS/Unicode-String-2.01"
>2.01
  (GAAS on 1998-01-21)</option>
<option
  
  value="GAAS/Unicode-String-2.00"
>2.00
  (GAAS on 1998-01-19)</option>
</optgroup>
</select>
    </li>
    <li class="version-diff">
<select onchange="document.location.href='/release/GAAS/Unicode-String-2.10/diff/' + encodeURIComponent(this.value) + '/String.pm'
" class="form-control tool-bar-form">
  <option disabled selected>Diff with version</option>
<option
  disabled
  value="GAAS/Unicode-String-2.10"
>2.10
  (GAAS on 2016-09-08)</option>
<option
  
  value="GAAS/Unicode-String-2.09"
>2.09
  (GAAS on 2005-10-26)</option>
<optgroup label="BackPAN">'
<option
  
  value="GAAS/Unicode-String-2.08"
>2.08
  (GAAS on 2005-10-25)</option>
<option
  
  value="GAAS/Unicode-String-2.07"
>2.07
  (GAAS on 2003-03-11)</option>
<option
  
  value="GAAS/Unicode-String-2.06"
>2.06
  (GAAS on 2000-05-19)</option>
<option
  
  value="GAAS/Unicode-String-2.05"
>2.05
  (GAAS on 1999-11-17)</option>
<option
  
  value="GAAS/Unicode-String-2.04"
>2.04
  (GAAS on 1999-09-14)</option>
<option
  
  value="GAAS/Unicode-String-2.03"
>2.03
  (GAAS on 1999-07-28)</option>
<option
  
  value="GAAS/Unicode-String-2.02"
>2.02
  (GAAS on 1999-05-01)</option>
<option
  
  value="GAAS/Unicode-String-2.01"
>2.01
  (GAAS on 1998-01-21)</option>
<option
  
  value="GAAS/Unicode-String-2.00"
>2.00
  (GAAS on 1998-01-19)</option>
</optgroup>
</select>
    </li>

    <li>
<ul class="dependencies">
  <li class="nav-header">Dependencies</li>
  <li><a href="https://metacpan.org/pod/MIME::Base64" title="MIME::Base64" class="ellipsis">MIME::Base64</a></li>
  <li><i class="ttip" title="dynamic_config enabled">and possibly others</i></li>
  <li>
    <hr>
  </li>
  <li>
    <a href="https://metacpan.org/module/Unicode::String/requires">Reverse dependencies</a>
  </li>
  <li>
    <a href="http://deps.cpantesters.org/?module=Unicode%3A%3AString">CPAN Testers List</a>
  </li>
  <li>
    <a href="https://cpandeps.grinnz.com/?dist=Unicode-String">Dependency graph</a>
  </li>
</ul>
    </li>
    <li class="nav-header">Permalinks</li>
    <li>
      <a href="https://metacpan.org/release/GAAS/Unicode-String-2.10/view/String.pm">This version</a>
    </li>
    <li>
      <a href="./Unicode::String.html">Latest version</a>
    </li>
    <li>
<div class="plussers">
<div class="nav-header">++ed by:</div>
<div>
<a class="display-all" href="https://metacpan.org/author/PAWAPAWA"><img src="https://www.gravatar.com/avatar/96d37e9730b6fe228338ce866c103daa?d=identicon&amp;s=20" title="PAWAPAWA" alt="PAWAPAWA"></a>
<a class="display-all" href="https://metacpan.org/author/EMAZEP"><img src="https://www.gravatar.com/avatar/a700b943268e8937ffd425389d962787?d=identicon&amp;s=20" title="EMAZEP" alt="EMAZEP"></a>
<a class="display-all" href="https://metacpan.org/author/KEEDI"><img src="https://www.gravatar.com/avatar/95f905a7a4ccc573c711e9d264c0fde8?d=identicon&amp;s=20" title="KEEDI" alt="KEEDI"></a>
</div>
<!-- Display counts of plussers-->
<div>
    <a href="https://metacpan.org/dist/Unicode-String/plussers">3 PAUSE users</a>
</div>
<div>
    2 non-PAUSE users
</div>
</div>
    </li>
    <li>
    </li>
              </ul>
            </div>
          </nav>
          <div class="content-navigation">
<div class="breadcrumbs">
  <span>
    <a data-keyboard-shortcut="g a" rel="author" href="https://metacpan.org/author/GAAS" class="author-name">Gisle Aas</a>
  </span>
  <span>&nbsp;/&nbsp;</span>
  <div class="release dist-release status-latest maturity-released">
    <span class="dropdown"><b class="caret"></b></span>
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/String.pm&#39;" class="">
<option
  selected
  value="GAAS/Unicode-String-2.10"
>2.10
  (GAAS on 2016-09-08)</option>
<option
  
  value="GAAS/Unicode-String-2.09"
>2.09
  (GAAS on 2005-10-26)</option>
<optgroup label="BackPAN">'
<option
  
  value="GAAS/Unicode-String-2.08"
>2.08
  (GAAS on 2005-10-25)</option>
<option
  
  value="GAAS/Unicode-String-2.07"
>2.07
  (GAAS on 2003-03-11)</option>
<option
  
  value="GAAS/Unicode-String-2.06"
>2.06
  (GAAS on 2000-05-19)</option>
<option
  
  value="GAAS/Unicode-String-2.05"
>2.05
  (GAAS on 1999-11-17)</option>
<option
  
  value="GAAS/Unicode-String-2.04"
>2.04
  (GAAS on 1999-09-14)</option>
<option
  
  value="GAAS/Unicode-String-2.03"
>2.03
  (GAAS on 1999-07-28)</option>
<option
  
  value="GAAS/Unicode-String-2.02"
>2.02
  (GAAS on 1999-05-01)</option>
<option
  
  value="GAAS/Unicode-String-2.01"
>2.01
  (GAAS on 1998-01-21)</option>
<option
  
  value="GAAS/Unicode-String-2.00"
>2.00
  (GAAS on 1998-01-19)</option>
</optgroup>
</select>
    <a data-keyboard-shortcut="g d" class="release-name" href="https://metacpan.org/dist/Unicode-String">Unicode-String-2.10</a>
  </div>
<span class="river-gauge-gauge">
  <svg width="24px"
       height="15px"
       version="1.1"
       xmlns="http://www.w3.org/2000/svg"
       xmlns:xlink="http://www.w3.org/1999/xlink">

    <g>
      <title>        River stage two &#10;
          • 17 direct dependents &#10;          • 32 total dependents
      </title>

      <rect x="0"  y="0" width="4" height="15" fill="#7ea3f2" />
      <rect x="5"  y="0" width="4" height="15" fill="#7ea3f2" />
      <rect x="10"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="15"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="20"  y="0" width="4" height="15" fill="#e4e2e2" />
    </g>
  </svg>

</span>
<div id="Unicode-String-fav" class="logged_in">
<form action="https://metacpan.org/account/favorite/add" style="display: inline" onsubmit="return favDistribution(this)">
    <input type="hidden" name="remove" value="0">
    <input type="hidden" name="release" value="Unicode-String-2.10">
    <input type="hidden" name="author" value="GAAS">
    <input type="hidden" name="distribution" value="Unicode-String">
    <button type="submit" class="favorite highlight"><span>5</span> ++</button>
</form>
</div>
<div class="logged_out">
<a href="./Unicode::String.html" onclick="alert('Please sign in to add favorites'); return false" class="favorite highlight">
<span>5</span> ++</a>
</div>
   / <span>Unicode::String</span>
</div>
          </div>
          <main class="content">


<nav class="toc">
  <div class="toc-header"><strong>Contents</strong></div>
<ul>
  <li><a href="./Unicode::String.html#NAME">NAME</a></li>
  <li><a href="./Unicode::String.html#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="./Unicode::String.html#DESCRIPTION">DESCRIPTION</a>
    <ul>
      <li><a href="./Unicode::String.html#METHODS">METHODS</a></li>
      <li><a href="./Unicode::String.html#Class-methods">Class methods</a></li>
      <li><a href="./Unicode::String.html#Encoding-methods">Encoding methods</a></li>
      <li><a href="./Unicode::String.html#String-Operations">String Operations</a></li>
    </ul>
  </li>
  <li><a href="./Unicode::String.html#FUNCTIONS">FUNCTIONS</a></li>
  <li><a href="./Unicode::String.html#SEE-ALSO">SEE ALSO</a></li>
  <li><a href="./Unicode::String.html#COPYRIGHT">COPYRIGHT</a></li>
</ul></nav>
<div class="pod anchors">
<h1 id="NAME">NAME</h1>

<p>Unicode::String - String of Unicode characters (UTF-16BE)</p>

<h1 id="SYNOPSIS">SYNOPSIS</h1>

<pre><code> use Unicode::String qw(utf8 latin1 utf16be);

 $u = utf8(&quot;string&quot;);
 $u = latin1(&quot;string&quot;);
 $u = utf16be(&quot;\0s\0t\0r\0i\0n\0g&quot;);

 print $u-&gt;utf32be;   # 4 byte characters
 print $u-&gt;utf16le;   # 2 byte characters + surrogates
 print $u-&gt;utf8;      # 1-4 byte characters</code></pre>

<h1 id="DESCRIPTION">DESCRIPTION</h1>

<p>A <code>Unicode::String</code> object represents a sequence of Unicode characters. Methods are provided to convert between various external formats (encodings) and <code>Unicode::String</code> objects, and methods are provided for common string manipulations.</p>

<p>The functions utf32be(), utf32le(), utf16be(), utf16le(), utf8(), utf7(), latin1(), uhex(), uchr() can be imported from the <code>Unicode::String</code> module and will work as constructors initializing strings of the corresponding encoding.</p>

<p>The <code>Unicode::String</code> objects overload various operators, which means that they in most cases can be treated like plain strings.</p>

<p>Internally a <code>Unicode::String</code> object is represented by a string of 2 byte numbers in network byte order (big-endian). This representation is not visible by the API provided, but it might be useful to know in order to predict the efficiency of the provided methods.</p>

<h2 id="METHODS">METHODS</h2>

<h2 id="Class-methods"><a id="Class"></a>Class methods</h2>

<p>The following class methods are available:</p>

<dl>

<dt id="Unicode::String-&gt;stringify_as"><a id="Unicode"></a><a id="Unicode::String--stringify_as"></a>Unicode::String-&gt;stringify_as</dt>
<dd>

</dd>
<dt id="Unicode::String-&gt;stringify_as(-$enc-)"><a id="Unicode1"></a><a id="Unicode::String--stringify_as---enc"></a>Unicode::String-&gt;stringify_as( $enc )</dt>
<dd>

<p>This method is used to specify which encoding will be used when <code>Unicode::String</code> objects are implicitly converted to and from plain strings.</p>

<p>If an argument is provided it sets the current encoding. The argument should have one of the following: &quot;ucs4&quot;, &quot;utf32&quot;, &quot;utf32be&quot;, &quot;utf32le&quot;, &quot;ucs2&quot;, &quot;utf16&quot;, &quot;utf16be&quot;, &quot;utf16le&quot;, &quot;utf8&quot;, &quot;utf7&quot;, &quot;latin1&quot; or &quot;hex&quot;. The default is &quot;utf8&quot;.</p>

<p>The stringify_as() method returns a reference to the current encoding function.</p>

</dd>
<dt id="$us-=-Unicode::String-&gt;new"><a id="us---Unicode::String--new"></a>$us = Unicode::String-&gt;new</dt>
<dd>

</dd>
<dt id="$us-=-Unicode::String-&gt;new(-$initial_value-)"><a id="us---Unicode::String--new---initial_value"></a>$us = Unicode::String-&gt;new( $initial_value )</dt>
<dd>

<p>This is the object constructor. Without argument, it creates an empty <code>Unicode::String</code> object. If an $initial_value argument is given, it is decoded according to the specified stringify_as() encoding, UTF-8 by default.</p>

<p>In general it is recommended to import and use one of the encoding specific constructor functions instead of invoking this method.</p>

</dd>
</dl>

<h2 id="Encoding-methods"><a id="Encoding"></a>Encoding methods</h2>

<p>These methods get or set the value of the <code>Unicode::String</code> object by passing strings in the corresponding encoding. If a new value is passed as argument it will set the value of the <code>Unicode::String</code>, and the previous value is returned. If no argument is passed then the current value is returned.</p>

<p>To illustrate the encodings we show how the 2 character sample string of &quot;&micro;m&quot; (micro meter) is encoded for each one.</p>

<dl>

<dt id="$us-&gt;utf32be"><a id="us--utf32be"></a>$us-&gt;utf32be</dt>
<dd>

</dd>
<dt id="$us-&gt;utf32be(-$newval-)"><a id="us--utf32be---newval"></a>$us-&gt;utf32be( $newval )</dt>
<dd>

<p>The string passed should be in the UTF-32 encoding with bytes in big endian order. The sample &quot;&micro;m&quot; is &quot;\0\0\0\xB5\0\0\0m&quot; in this encoding.</p>

<p>Alternative names for this method are utf32() and ucs4().</p>

</dd>
<dt id="$us-&gt;utf32le"><a id="us--utf32le"></a>$us-&gt;utf32le</dt>
<dd>

</dd>
<dt id="$us-&gt;utf32le(-$newval-)"><a id="us--utf32le---newval"></a>$us-&gt;utf32le( $newval )</dt>
<dd>

<p>The string passed should be in the UTF-32 encoding with bytes in little endian order. The sample &quot;&micro;m&quot; is is &quot;\xB5\0\0\0m\0\0\0&quot; in this encoding.</p>

</dd>
<dt id="$us-&gt;utf16be"><a id="us--utf16be"></a>$us-&gt;utf16be</dt>
<dd>

</dd>
<dt id="$us-&gt;utf16be(-$newval-)"><a id="us--utf16be---newval"></a>$us-&gt;utf16be( $newval )</dt>
<dd>

<p>The string passed should be in the UTF-16 encoding with bytes in big endian order. The sample &quot;&micro;m&quot; is &quot;\0\xB5\0m&quot; in this encoding.</p>

<p>Alternative names for this method are utf16() and ucs2().</p>

<p>If the string passed to utf16be() starts with the Unicode byte order mark in little endian order, the result is as if utf16le() was called instead.</p>

</dd>
<dt id="$us-&gt;utf16le"><a id="us--utf16le"></a>$us-&gt;utf16le</dt>
<dd>

</dd>
<dt id="$us-&gt;utf16le(-$newval-)"><a id="us--utf16le---newval"></a>$us-&gt;utf16le( $newval )</dt>
<dd>

<p>The string passed should be in the UTF-16 encoding with bytes in little endian order. The sample &quot;&micro;m&quot; is is &quot;\xB5\0m\0&quot; in this encoding. This is the encoding used by the Microsoft Windows API.</p>

<p>If the string passed to utf16le() starts with the Unicode byte order mark in big endian order, the result is as if utf16le() was called instead.</p>

</dd>
<dt id="$us-&gt;utf8"><a id="us--utf8"></a>$us-&gt;utf8</dt>
<dd>

</dd>
<dt id="$us-&gt;utf8(-$newval-)"><a id="us--utf8---newval"></a>$us-&gt;utf8( $newval )</dt>
<dd>

<p>The string passed should be in the UTF-8 encoding. The sample &quot;&micro;m&quot; is &quot;\xC2\xB5m&quot; in this encoding.</p>

</dd>
<dt id="$us-&gt;utf7"><a id="us--utf7"></a>$us-&gt;utf7</dt>
<dd>

</dd>
<dt id="$us-&gt;utf7(-$newval-)"><a id="us--utf7---newval"></a>$us-&gt;utf7( $newval )</dt>
<dd>

<p>The string passed should be in the UTF-7 encoding. The sample &quot;&micro;m&quot; is &quot;+ALU-m&quot; in this encoding.</p>

<p>The UTF-7 encoding only use plain US-ASCII characters for the encoding. This makes it safe for transport through 8-bit stripping protocols. Characters outside the US-ASCII range are base64-encoded and &#39;+&#39; is used as an escape character. The UTF-7 encoding is described in RFC 1642.</p>

<p>If the (global) variable $Unicode::String::UTF7_OPTIONAL_DIRECT_CHARS is TRUE, then a wider range of characters are encoded as themselves. It is even TRUE by default. The characters affected by this are:</p>

<pre><code>   ! &quot; # $ % &amp; * ; &lt; = &gt; @ [ ] ^ _ ` { | }</code></pre>

</dd>
<dt id="$us-&gt;latin1"><a id="us--latin1"></a>$us-&gt;latin1</dt>
<dd>

</dd>
<dt id="$us-&gt;latin1(-$newval-)"><a id="us--latin1---newval"></a>$us-&gt;latin1( $newval )</dt>
<dd>

<p>The string passed should be in the ISO-8859-1 encoding. The sample &quot;&micro;m&quot; is &quot;\xB5m&quot; in this encoding.</p>

<p>Characters outside the &quot;\x00&quot; .. &quot;\xFF&quot; range are simply removed from the return value of the latin1() method. If you want more control over the mapping from Unicode to ISO-8859-1, use the <code>Unicode::Map8</code> class. This is also the way to deal with other 8-bit character sets.</p>

</dd>
<dt id="$us-&gt;hex"><a id="us--hex"></a>$us-&gt;hex</dt>
<dd>

</dd>
<dt id="$us-&gt;hex(-$newval-)"><a id="us--hex---newval"></a>$us-&gt;hex( $newval )</dt>
<dd>

<p>The string passed should be plain ASCII where each Unicode character is represented by the &quot;U+XXXX&quot; string and separated by a single space character. The &quot;U+&quot; prefix is optional when setting the value. The sample &quot;&micro;m&quot; is &quot;U+00b5 U+006d&quot; in this encoding.</p>

</dd>
</dl>

<h2 id="String-Operations"><a id="String"></a>String Operations</h2>

<p>The following methods are available:</p>

<dl>

<dt id="$us-&gt;as_string"><a id="us--as_string"></a>$us-&gt;as_string</dt>
<dd>

<p>Converts a <code>Unicode::String</code> to a plain string according to the setting of stringify_as(). The default stringify_as() encoding is &quot;utf8&quot;.</p>

</dd>
<dt id="$us-&gt;as_num"><a id="us--as_num"></a>$us-&gt;as_num</dt>
<dd>

<p>Converts a <code>Unicode::String</code> to a number. Currently only the digits in the range 0x30 .. 0x39 are recognized. The plan is to eventually support all Unicode digit characters.</p>

</dd>
<dt id="$us-&gt;as_bool"><a id="us--as_bool"></a>$us-&gt;as_bool</dt>
<dd>

<p>Converts a <code>Unicode::String</code> to a boolean value. Only the empty string is FALSE. A string consisting of only the character U+0030 is considered TRUE, even if Perl consider &quot;0&quot; to be FALSE.</p>

</dd>
<dt id="$us-&gt;repeat(-$count-)"><a id="us--repeat---count"></a>$us-&gt;repeat( $count )</dt>
<dd>

<p>Returns a new <code>Unicode::String</code> where the content of $us is repeated $count times. This operation is also overloaded as:</p>

<pre><code>  $us x $count</code></pre>

</dd>
<dt id="$us-&gt;concat(-$other_string-)"><a id="us--concat---other_string"></a>$us-&gt;concat( $other_string )</dt>
<dd>

<p>Concatenates the string $us and the string $other_string. If $other_string is not an <code>Unicode::String</code> object, then it is first passed to the Unicode::String-&gt;new constructor function. This operation is also overloaded as:</p>

<pre><code>  $us . $other_string</code></pre>

</dd>
<dt id="$us-&gt;append(-$other_string-)"><a id="us--append---other_string"></a>$us-&gt;append( $other_string )</dt>
<dd>

<p>Appends the string $other_string to the value of $us. If $other_string is not an <code>Unicode::String</code> object, then it is first passed to the Unicode::String-&gt;new constructor function. This operation is also overloaded as:</p>

<pre><code>  $us .= $other_string</code></pre>

</dd>
<dt id="$us-&gt;copy"><a id="us--copy"></a>$us-&gt;copy</dt>
<dd>

<p>Returns a copy of the current <code>Unicode::String</code> object. This operation is overloaded as the assignment operator.</p>

</dd>
<dt id="$us-&gt;length"><a id="us--length"></a>$us-&gt;length</dt>
<dd>

<p>Returns the length of the <code>Unicode::String</code>. Surrogate pairs are still counted as 2.</p>

</dd>
<dt id="$us-&gt;byteswap"><a id="us--byteswap"></a>$us-&gt;byteswap</dt>
<dd>

<p>This method will swap the bytes in the internal representation of the <code>Unicode::String</code> object.</p>

<p>Unicode reserve the character U+FEFF character as a byte order mark. This works because the swapped character, U+FFFE, is reserved to not be valid. For strings that have the byte order mark as the first character, we can guaranty to get the byte order right with the following code:</p>

<pre><code>   $ustr-&gt;byteswap if $ustr-&gt;ord == 0xFFFE;</code></pre>

</dd>
<dt id="$us-&gt;unpack"><a id="us--unpack"></a>$us-&gt;unpack</dt>
<dd>

<p>Returns a list of integers each representing an UCS-2 character code.</p>

</dd>
<dt id="$us-&gt;pack(-@uchr-)"><a id="us--pack---uchr"></a>$us-&gt;pack( @uchr )</dt>
<dd>

<p>Sets the value of $us as a sequence of UCS-2 characters with the characters codes given as parameter.</p>

</dd>
<dt id="$us-&gt;ord"><a id="us--ord"></a>$us-&gt;ord</dt>
<dd>

<p>Returns the character code of the first character in $us. The ord() method deals with surrogate pairs, which gives us a result-range of 0x0 .. 0x10FFFF. If the $us string is empty, undef is returned.</p>

</dd>
<dt id="$us-&gt;chr(-$code-)"><a id="us--chr---code"></a>$us-&gt;chr( $code )</dt>
<dd>

<p>Sets the value of $us to be a string containing the character assigned code $code. The argument $code must be an integer in the range 0x0 .. 0x10FFFF. If the code is greater than 0xFFFF then a surrogate pair created.</p>

</dd>
<dt id="$us-&gt;name"><a id="us--name"></a>$us-&gt;name</dt>
<dd>

<p>In scalar context returns the official Unicode name of the first character in $us. In array context returns the name of all characters in $us. Also see <a href="https://metacpan.org/pod/Unicode::CharName">Unicode::CharName</a>.</p>

</dd>
<dt id="$us-&gt;substr(-$offset-)"><a id="us--substr---offset"></a>$us-&gt;substr( $offset )</dt>
<dd>

</dd>
<dt id="$us-&gt;substr(-$offset,-$length-)"><a id="us--substr---offset---length"></a>$us-&gt;substr( $offset, $length )</dt>
<dd>

</dd>
<dt id="$us-&gt;substr(-$offset,-$length,-$subst-)"><a id="us--substr---offset---length---subst"></a>$us-&gt;substr( $offset, $length, $subst )</dt>
<dd>

<p>Returns a sub-string of $us. Works similar to the builtin substr() function.</p>

</dd>
<dt id="$us-&gt;index(-$other-)"><a id="us--index---other"></a>$us-&gt;index( $other )</dt>
<dd>

</dd>
<dt id="$us-&gt;index(-$other,-$pos-)"><a id="us--index---other---pos"></a>$us-&gt;index( $other, $pos )</dt>
<dd>

<p>Locates the position of $other within $us, possibly starting the search at position $pos.</p>

</dd>
<dt id="$us-&gt;chop"><a id="us--chop"></a>$us-&gt;chop</dt>
<dd>

<p>Chops off the last character of $us and returns it (as a <code>Unicode::String</code> object).</p>

</dd>
</dl>

<h1 id="FUNCTIONS">FUNCTIONS</h1>

<p>The following functions are provided. None of these are exported by default.</p>

<dl>

<dt id="byteswap2(-$str,-...-)"><a id="byteswap2"></a><a id="byteswap2---str"></a>byteswap2( $str, ... )</dt>
<dd>

<p>This function will swap 2 and 2 bytes in the strings passed as arguments. If this function is called in void context, then it will modify its arguments in-place. Otherwise, the swapped strings are returned.</p>

</dd>
<dt id="byteswap4(-$str,-...-)"><a id="byteswap4"></a><a id="byteswap4---str"></a>byteswap4( $str, ... )</dt>
<dd>

<p>The byteswap4 function works similar to byteswap2, but will reverse the order of 4 and 4 bytes.</p>

</dd>
<dt id="latin1(-$str-)"><a id="latin1"></a><a id="latin1---str"></a>latin1( $str )</dt>
<dd>

</dd>
<dt id="utf7(-$str-)"><a id="utf7"></a><a id="utf7---str"></a>utf7( $str )</dt>
<dd>

</dd>
<dt id="utf8(-$str-)"><a id="utf8"></a><a id="utf8---str"></a>utf8( $str )</dt>
<dd>

</dd>
<dt id="utf16le(-$str-)"><a id="utf16le"></a><a id="utf16le---str"></a>utf16le( $str )</dt>
<dd>

</dd>
<dt id="utf16be(-$str-)"><a id="utf16be"></a><a id="utf16be---str"></a>utf16be( $str )</dt>
<dd>

</dd>
<dt id="utf32le(-$str-)"><a id="utf32le"></a><a id="utf32le---str"></a>utf32le( $str )</dt>
<dd>

</dd>
<dt id="utf32be(-$str-)"><a id="utf32be"></a><a id="utf32be---str"></a>utf32be( $str )</dt>
<dd>

<p>Constructor functions for the various Unicode encodings. These return new <code>Unicode::String</code> objects. The provided argument should be encoded correspondingly.</p>

</dd>
<dt id="uhex(-$str-)"><a id="uhex"></a><a id="uhex---str"></a>uhex( $str )</dt>
<dd>

<p>Constructs a new <code>Unicode::String</code> object from a string of hex values. See hex() method above for description of the format.</p>

</dd>
<dt id="uchar(-$num-)"><a id="uchar"></a><a id="uchar---num"></a>uchar( $num )</dt>
<dd>

<p>Constructs a new one character <code>Unicode::String</code> object from a Unicode character code. This works similar to perl&#39;s builtin chr() function.</p>

</dd>
</dl>

<h1 id="SEE-ALSO"><a id="SEE"></a>SEE ALSO</h1>

<p><a href="https://metacpan.org/pod/Unicode::CharName">Unicode::CharName</a>, <a href="./Unicode::Map8.html">Unicode::Map8</a></p>

<p><a href="http://www.unicode.org/">http://www.unicode.org/</a></p>

<p><a href="https://metacpan.org/pod/perlunicode">perlunicode</a></p>

<h1 id="COPYRIGHT">COPYRIGHT</h1>

<p>Copyright 1997-2000,2005 Gisle Aas.</p>

<p>This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.</p>

<div class="pod-errors"><p>1 POD Error</p><div class="pod-errors-detail"><p>The following errors were encountered while parsing the POD:</p><dl><dt>Around line 600:</dt><dd><p>Non-ASCII character seen before =encoding in &#39;&quot;&micro;m&quot;&#39;. Assuming CP1252</p></dd></dl></div></div></div>

<div id="metacpan_install-instructions-dialog" class="modal fade">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
        <h4 class="modal-title">Module Install Instructions</h4>
      </div>
      <div class="modal-body">
        <p>To install Unicode::String, copy and paste the appropriate command in to your terminal.</p>
        <p><a href="https://metacpan.org/dist/App-cpanminus/view/bin/cpanm">cpanm</a></p>
        <pre><code>cpanm Unicode::String</code></pre>
        <p><a href="https://metacpan.org/pod/CPAN">CPAN shell</a></p>
        <pre><code>perl -MCPAN -e shell
install Unicode::String</code></pre>
        <p>For more information on module installation, please visit <a href="https://www.cpan.org/modules/INSTALL.html">the detailed CPAN module installation guide</a>.</p>
      </div>
      <div class="modal-footer">
        <a href="./Unicode::String.html#" data-dismiss="modal" class="btn">Close</a>
      </div>
    </div>
  </div>
</div>
          </main>
          <div class="content-pagination">
          </div>
        </div>
        <footer class="footer">
          <div class="footer-container">
            <div class="footer-social">
              <div class="footer-link footer-logo">
                <a href="https://metacpan.org/">
                  <img src="https://metacpan.org/static/images/metacpan-logo.svg" alt="MetaCPAN" />
                </a>
              </div>
              <a class="footer-social-link" href="https://github.com/metacpan">
                <i class="fab fa-github-square"></i>
              </a>
              <a class="footer-social-link" href="https://fosstodon.org/@metacpan">
                <i class="fab fa-mastodon"></i>
              </a>
            </div>
            <div class="footer-links">
              <div class="footer-link">
                  <a href="https://metacpan.org/about">About</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/sponsors">Sponsor</a>
              </div>
              <div class="footer-link">
                  <a href="https://grep.metacpan.org">grep::cpan</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/recent">Recent</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/faq">FAQ</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/tools">Tools</a>
              </div>
              <div class="footer-link">
                  <a href="https://fastapi.metacpan.org/">API</a>
              </div>
              <div class="footer-link">
                  <a href="https://www.perl.org/">Perl.org</a>
              </div>
            </div>
            <div class="footer-sponsors">
              <a class="footer-sponsor-link" target="_blank" href="https://www.bytemark.co.uk/" rel="noopener">
                <img class="footer-sponsor-bytemark" src="https://metacpan.org/static/images/sponsors/bytemark_logo.svg" alt="Bytemark logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.liquidweb.com/" rel="noopener">
                <img class="footer-sponsor-liquidweb" src="https://metacpan.org/static/images/sponsors/liquidweb_logo.png" alt="liquidweb logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://deriv.com/careers/" rel="noopener">
                <img class="footer-sponsor-deriv" src="https://metacpan.org/static/images/sponsors/deriv.svg" alt="Deriv logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://geocode.xyz" rel="noopener">
                <img class="footer-sponsor-geocode" src="https://metacpan.org/static/images/sponsors/geocodelogo.svg" alt="Geocode logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.fastly.com/" rel="noopener">
                <img class="footer-sponsor-fastly" src="https://metacpan.org/static/images/sponsors/fastly_logo.svg" alt="Fastly logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://opencagedata.com" rel="noopener">
                <img class="footer-sponsor-opencage" src="https://metacpan.org/static/images/sponsors/open-cage.svg" alt="OpenCage logo">
              </a>
            </div>
          </div>
        </footer>
        <div class="modal fade" tabindex="-1" role="dialog" id="metacpan_keyboard-shortcuts">
          <div class="modal-dialog">
            <div class="modal-content">
              <div class="modal-header">
                <button type="button" class="close" data-dismiss="modal">&times;</button>
                <h4 class="modal-title">Keyboard Shortcuts</h4>
              </div>
              <div class="modal-body row">
<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Global</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>s</kbd>
        </td>
        <td>Focus search bar</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>?</kbd>
        </td>
        <td>Bring up this help dialog</td>
      </tr>
    </tbody>
  </table>

  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>GitHub</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>p</kbd>
        </td>
        <td>Go to pull requests</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>go to github issues (only if github is preferred repository)</td>
      </tr>
    </tbody>
  </table>
</div>

<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>POD</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>a</kbd>
        </td>
        <td>Go to author</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>c</kbd>
        </td>
        <td>Go to changes</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>Go to issues</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>d</kbd>
        </td>
        <td>Go to dist</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>r</kbd>
        </td>
        <td>Go to repository/SCM</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>s</kbd>
        </td>
        <td>Go to source</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>b</kbd>
        </td>
        <td>Go to file browse</td>
      </tr>

    </tbody>
  </table>
</div>

<div class="col-md-12">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Search terms</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><em>module:</em> (e.g. <a href="https://metacpan.org/search?q=module%3APlugin">module:Plugin</a>)</td>
      </tr>
      <tr>
        <td><em>distribution:</em> (e.g. <a href="https://metacpan.org/search?q=distribution%3ADancer+auth">distribution:Dancer auth</a>)</td>
      </tr>
      <tr>
        <td><em>author:</em> (e.g. <a href="https://metacpan.org/search?q=author%3ASONGMU+Redis">author:SONGMU Redis</a>)</td>
      </tr>
      <tr>
        <td><em>version:</em> (e.g. <a href="https://metacpan.org/search?q=version%3A1.00">version:1.00</a>)</td>
      </tr>
    </tbody>
  </table>
</div>
              </div>
              <div class="modal-footer"></div>
            </div>
          </div>
        </div>
    </body>
</html>
